$webwork.htmlEncode($page.space.name) : 2 Files

The two central configuration files are services.xml and catalog.xml. In the source tree they are located in the conf/ directory. In the created wars they are copied to the WEB-INF/ directory. This is a little out of the way, as it would make sense for them to live with the other configuration files, but they are placed in WEB-INF/ so they are hidden from users. Servlet containers often make all files not in WEB-INF/ viewable, and catalog.xml in particular contains sensitive passwords and configuration information.

The rest of the conf/ folder is copied to geoserver/data/. The decision was made to make this information accessible to users, as it is just meta information. Users can also place additional files that relate to their featuretypes, such as metadata about the layers. A past version of GeoServer offered z39.50 catalog support using metadata files in the featureType folders, and future versions will likely bring it back (especially if there is interest, please email us if you would like integrated z39.50 geo profile support).

Services.xml

The services.xml file contains configuration options for the server (like the maximum number of features to return, the logging level, the admin username and password, ect.) as well as meta information for the WMS and WFS. This meta information is primarily what would appear in a Capabilities document for either, such as the name and title of the server, keywords, ect. A sample services.xml file is as follows:

<?xml version="1.0" encoding="iso-8859-1"?>
<serverConfiguration>
  <global>

      <!-- Defines the logging level.  Common options are SEVERE,
           WARNING, INFO, CONFIG, FINE, FINER, FINEST, in order of
           Increasing statements logged.
       -->
     <loggingLevel>FINE</loggingLevel>

     <!-- Sets the maximum features returned by GeoServer.  This used to
          be necessary, due to out of memory errors.  The server is much
          more scalable now, but admins may use it to limit the amount of
          data returned, so naive clients don't ask for megabytes.
       -->
     <maxFeatures value="1000000"/>

     <!-- Sets if the xml returned should have line feeds and indents. 
          The default is true.  Setting it to false will cut down on
          the amount of blank spaces returned to clients, and is recommended
          if humans will not read the output -->

     <verbose value="false"/>

     <!-- Sets the max number of decimal places past the zero returned in
          the gml coordinates of a GetFeature response.  Default is 4 -->
     <numDecimals value="8"/>
     
     <!-- The user name of the administrator of this machine.  Used for   -->
     <!-- logging in to the web administration tool.                      -->
     <adminUserName>admin</adminUserName>

       
     <!-- The user name of the administrator of this machine.  Used for   -->
     <!-- logging in to the web administration tool.                      -->
     <adminPassword>geoserver</adminPassword>

     <!-- contact information -->
     <ContactInformation>

       <ContactPersonPrimary>
         <ContactPerson>Chris Holmes</ContactPerson>
         <ContactOrganization>The Open Planning Project</ContactOrganization>
       </ContactPersonPrimary>
     </ContactInformation>

  </global>
  <services>
    <service type="WFS" enabled="true">
      <!-- Service elements, needed for the capabilities document -->
      <!-- Title and OnlineResource are the two required -->
      <name>My GeoServer WFS</name>

      <title>My GeoServer WFS</title>
      <abstract>This is a description of your Web Feature Server.</abstract>
      <keywords>
        <keyword>WFS</keyword>

        <keyword>GEOSERVER</keyword>
      </keywords>
      <onlineResource>http://geoserver.sourceforge.net/html/index.php</onlineResource>
      <fees>NONE</fees>

      <accessConstraints>NONE</accessConstraints>
      <maintainer>http://jira.codehaus.org/secure/BrowseProject.jspa?id=10311</maintainer>
      <!-- Sets whether name, description and boundedBy elements should   -->
      <!-- have a gml: prefix instead of the standard one for the feature -->
      <!-- It is a bit of a hack, and should generally only be used with  -->

      <!-- the cite tests for now.  In the future it should all be done   -->
      <!-- automatically -->
      <gmlPrefixing value="false"/>
      <!-- Sets the service level ie whether transaction operations are   -->
      <!-- enabled or not.  -->
      <serviceLevel>Complete</serviceLevel>

    </service>

    <service type="WMS" enabled="true">
      <!-- Service elements, needed for the capabilities document -->
      <!-- Title and OnlineResource are the two required -->
      <name>My GeoServer WMS</name>

      <title>My GeoServer WMS</title>
      <abstract> This is a description of your Web Map Server.</abstract>
      <keywords>
        <keyword>WMS</keyword>

      </keywords>
      <onlineResource>http://geoserver.sourceforge.net/html/index.php</onlineResource>
      <fees>NONE</fees>
      <accessConstraints>NONE</accessConstraints>

    </service>

  </services>
</serverConfiguration>

As you can see it is divided into to main sections, global, which defines configuration options for all of GeoServer, and Service, which defines meta information for the individual service's capabilities documents, as well as a few service specific config items. <

Catalog.xml

The catalog.xml file is the place that stores configuration of DataStores, Namespaces, and Styles. A sample catalog files looks like this:

<?xml version="1.0" encoding="UTF-8"?>

<catalog>
  <datastores>
    <!-- a datastore configuration element serves as a common data source -->
    <!-- connection parameters repository for all featuretypes it holds.  -->
    <datastore id="bc_shapefile"
               enabled="true"
               namespace="topp">
      <description>British Columbia sample road shapefiles</description>

      <connectionParams>
        <!-- For now the url value is relative to where GeoServer moves the -->
        <!-- featureTypes directory.  Everything in featureTypes moves to   -->
        <!-- data, so just put the relative location.  -->
        <parameter name="url" 
                   value="file:data/featureTypes/bc_roads/bc_roads.shp"/>
      </connectionParams>

    </datastore>
    <!-- Unfortunately all shapefiles have their own datastore definitions. -->
    <!-- With the other datastores it is possible to define one datastore   -->
    <!-- that is refered to by a number of featureTypes.                    -->
    <datastore id="states_shapefile"
               enabled="true"
               namespace="topp">
      <description>United States sample shapefile</description>

      <connectionParams>
        <!-- For now the url value is relative to where GeoServer moves the -->
        <!-- featureTypes directory.  Everything in featureTypes moves to   -->
        <!-- data, so just put the relative location.  -->
        <parameter name="url" 
                   value="file:data/featureTypes/states/states.shp"/>
      </connectionParams>

    </datastore>

    <!-- A sample postgis datastore. -->
    <datastore id="localPostgis" enabled="true" namespace="topp">
    <!-- enabled is optional, defaults to true.  If a dcmms database on the -->
    <!-- local machine (automatic installation available for windows users) -->
    <!-- then set enabled to true and define a new featureTyp with localpg  -->

    <!-- as the datastore id -->
      <description>My local postgis testing database</description>
      <connectionParams>
        <!-- Must always be postgis -->
        <parameter name="dbtype" value="postgis"/>

        <!-- Where postgis is running (can be a remote name or ip) --> 
        <parameter name="host" value="localhost"/>
        <!-- The port to connect to (5432 is postgresql default) -->
        <!-- Be sure postmaster is running with -i to accept connections -->
        <parameter name="port" value="5432"/>
        <!-- The name of the postgis database -->

        <parameter name="database" value="dcmms"/>
        <!-- The username and password to connect with -->
        <parameter name="user" value="postgres"/>
        <parameter name="passwd" value="postgres"/>
      </connectionParams>
    </datastore> 
  </datastores>

  <!-- Defines the namespaces to be used.  All dataStores must refer to a   -->
  <!-- namespace.  If two namespaces are required for the same database then-->
  <!-- it is possible to just define two datastores with different ids but  -->
  <!-- the same connection parameters.                                      -->
  <namespaces>
    <namespace uri="http://www.refractions.net/lakes" 
           prefix="lake"/>

    <!-- Setting a namespace as the default allows you to refer to the -->
    <!-- featureTypes it contains without prefixing them -->           
    <namespace uri="http://www.openplans.org/topp" 
           prefix="topp"
           default="true"/>
    <namespace uri="http://www.axios.es/geoserver" 
           prefix="biz"/>
  </namespaces>

  <!-- Style definitions - maps a style name to a file.  The style files  -->

  <!-- must be contained in the styles folder                             --> 
  <styles>
      <style id="dotty" filename="funkypolyshp.sld"/>
      <style id="green" filename="green.sld"/>
      <style id="normal" filename="normal.sld" default="true"/>
      <style id="population" filename="popshade.sld"/>

      <style id="manualVsWorkers" filename="usa_math.sld"/>
  </styles>

</catalog>

Each namespace consists of a URI, which should be a unique string, such as in a domain that you own, and a prefix, generally a 3 or 4 character string used as a shortcut in the returned XML documents. One of the namespaces may have a 'default' attribute set to true, as well. The default will show up first in the web administration interface, and requests that leave off a prefix are assumed to live in that namespace.

Each DataStore consists of an id, which its featureTypes use to refer to it, an enabled attribute, which must be set to true if the DataStore is to be used, a namespace, a description, and a number of connection parameters. The namespace is just a prefix, which must match a registered namespace element. If more than one namespace is desired for a single back end data base then a way around that is to register two DataStores with the exact same connection parameters but different namespaces. We would like to change this, but involves some fundamental changes, to both GeoServer and GeoTools. The description is just a human readable description, not used by the WMS or WFS (as they only have concepts of FeatureTypes/Layers, not where those come from). The connection parameters are what are used to find and connect to a given datastore. These must match a plug-in DataStore, they correspond directly to the PARAM classes of a DataStoreFactorySpi implementation in GeoTools, which allows GeoServer to be completely independent of GeoTools data loading classes, except through their interfaces. If the appropriate jars to process a given set of connectionParams are present then the DataStore will be loaded.

The styles section contains the names of the SLD files and their ids. The style files themselves must be stored in the styles/ directory (under conf/, moved to data/ in an installed GeoServer). The id is the name that clients will refer to a style by. This is one of the areas in need of most improvement, it should be reworked for 1.3, most likely removing references to files from the catalog.xml file, the names should be specified in the SLD files themselves.

Along with the styles/ directory there four other directories under conf/ that contain various configuration data (and thus are copied to geoserver/data in the webapp): featureTypes, demo, plugIns, and validation.

featureTypes/ files

FeatureType is the most important of the conf folder's additional directories, as it defines what Layers (FeatureTypes) GeoServer returns. Each FeatureType is defined in its own folder, generally named by datastoreid_featuretypename. The main file in this folder is the info.xml file, which defines meta information of the FeatureType, such as returned by a Capabilities Document. A sample info.xml file is as follows:

<?xml version="1.0" encoding="UTF-8"?> 

<featureType datastore="states_shapefile">
  <!-- the name of the featureType in the dataStore, for shapefile it 
       must match the filename. -->
  <name>states</name>
  <!-- EPSG code for the FeatureType -->
  <SRS>4326</SRS>

  <!-- service elements returned for the capabilities document. -->
  <title>USA Population</title>
  <abstract>This is some census data on the states.</abstract>
  <keywords>census, united states, state boundaries</keywords>

  <!-- The bounding box for this featureType, in lat long coords. -->
  <latLonBoundingBox dynamic="false"  minx="-74.27000" miny="40.50000" maxx="-73.80000" maxy="40.94000"/>
  <!-- default style, for when the layer is requested with a blank style -->
  <styles default="population"/>
  <LegendURL width="72" height="72">
      <Format>image/png</Format>

      <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink"
                      xlink:type="simple"
                      xlink:href="http://www.espace.ird.nc/legend/legend.png"/>
   </LegendURL>
</featureType>

The folder may also contain the data for the layer itself, such as in the case of shapefiles. Since each shapefile only defines one layer it can easily live in the same directory as its meta information.

The last file is not always present, it is the schema.xml file. This is a tricky file - if present it is used directly for a DescribeFeatureType response, but configuration information is also read from it. If it is absent then the DescribeFeatureType response is automatically generated by GeoServer with the default AttributeTypes of the DataStore (such as the columns of the table). If present the schema.xml file can control the order and presence of attributes, as well as if they are mandatory or not. For example, the sample bc_roads shapefile contains three attributes, 'the_geom', BTRN_BC_ID, and LENGTH. A GetFeature request with no schema.xml file yields features with all three attributes, in that order. But if a schema.xml files such as the following is added to the bc_roads directory, then the behavior changes:

<xs:complexType name="bc_roads_Type">

  <xs:complexContent>
    <xs:extension base="gml:AbstractFeatureType">
      <xs:sequence>
        <xs:element name="LENGTH" minOccurs="1" nillable="true" type="xs:double"/>
        <xs:element name="the_geom" minOccurs="0" nillable="true" type="gml:MultiLineStringPropertyType"/>
      </xs:sequence>

    </xs:extension>
  </xs:complexContent>
</xs:complexType>

Features returned will only have a LENGTH and a the_geom attribute. The BTRN_BC_ID is hidden. This is useful for just exposing certain attributes in a database to the public, other attributes in a table can be hidden. Note also that the order matches that of the schema.xml file. This is so that the returned GetFeature request will validate - in xml the order must match that of the schema (at least if it is a sequence). Also note that if a GetFeature request is made that only asks for 'the_geom' as a propertyName then LENGTH will still be returned in the response, since the schema.xml says that it has minOccurs=1, which means that an instance of bc_roads must always contain at the LENGTH property, or else it will not validate.

Since the schema.xml file is directly returned in a DescribeFeatureType response this means it can be further customized, with advanced schemas that are not easily generated. Note that since it is returned directly it must only define the complexType element, it must define one type. The rest of the response is generated, according to the DescribeFeatureType request, if multiple FeatureTypes in the same namespace are requested then the complex types are appropriately appended together. Note that the web admin interface even allows you to specify xml fragments for each attribute. We figured that this would cover 99% of the cases, and the last 1% could work directly with the schema.xml files. We realize that the decisions with schemas do privilege some ways of operating over others. If you have feedback on how you would actually like to work with the schema files please let us know. We felt that this was the best way to make it configurable through the user interface while also allowing a large degree of flexibility over the control. In the future we will likely review this, as one of the next major goals is to roll in support for complex object definitions, which will beg a rethinking of all this. The current approach is limited by the fact that all the attributes must match the names as they are in the back end data format. We want to be able to specify different names, and indeed to create new complex types (with nested xml attributes) from what is present. And the end goal is to allow those definitions to be the result of complex joins. If you are interested in such things please get in touch, as we can use all the help we can get on this complex problem.

demo/ Files

The next directory is the demo directory. This one is very simple, it just contains a number of sample requests for the 'demo' section of the web administration tool. Each file in the directory is put on the drop down selector. This is very useful for testing during development, as you can just save your longer xml requests here. The demo section has the nice functionality of providing an interface for post requests, and the demo folder will save these post requests. Currently all requests that end in .url are simply appended to the base url of the running geoserver, and the body is left blank. This will then issue a get request to GeoServer. A sample GetCapabilities wms request is a getMap.url file that just contains the following line:

wms?request=GetCapabilities

For a post request the file must end in .xml. Since GeoServer only supports post with WFS the assumption is made to send it to the wfs. Once we get wms requests we will improve this. A sample GetFeature.xml file looks as follows:

<!-- Performs a get feature with a bounding box filter.      -->

<!-- The BBOX filter is a convenience for a <Not><Disjoint>, -->
<!-- it fetches all features that spatially interact with the given box. -->
<!-- This example also shows how to request specific properties, in this -->
<!-- case we just get the LENGTH and the_geom -->
<wfs:GetFeature service="WFS" version="1.0.0"
  outputFormat="GML2"
  xmlns:topp="http://www.openplans.org/topp"
  xmlns:wfs="http://www.opengis.net/wfs"
  xmlns:ogc="http://www.opengis.net/ogc"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.opengis.net/wfs
                      http://schemas.opengis.net/wfs/1.0.0/WFS-basic.xsd">
  <wfs:Query typeName="topp:bc_roads">
    <wfs:PropertyName>topp:LENGTH</wfs:PropertyName>

    <wfs:PropertyName>topp:the_geom</wfs:PropertyName>
    <ogc:Filter>
      <ogc:BBOX>
        <ogc:PropertyName>the_geom</ogc:PropertyName>
        <gml:Box srsName="http://www.opengis.net/gml/srs/epsg.xml#27345">

           <gml:coordinates>489154,5433017 505234,5448023</gml:coordinates>
        </gml:Box>
      </ogc:BBOX>
   </ogc:Filter>
  </wfs:Query>

</wfs:GetFeature>

Validation Files

The last two directories are both related to validation. The plugIns/ directory defines the mapping between a validation class and the name and arguments that it is assigned in GeoServer. Each plugIn must conform to the plugInSchema.xsd file found in capabilities/validate. It contains the name and description, that are used for display in the GeoServer web admin interface, the class, which performs the actual validation, and zero or more arguments, that specify the argument name and type, which must be supplied to perform a validation. For more information check the geotools java docs for the validation package. A sample plugIn file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="pluginSchema" 
xmlns:gml="http://www.opengis.net/gml" xmlns:ogc="http://www.opengis.net/ogc" 
xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" 
xs:schemaLocation="pluginSchema /data/capabilities/validate/pluginSchema.xsd">
<name>Equality</name>
<description>Checks for equality between a set value and a feature.</description>

<class>org.geotools.validation.attributes.EqualityValidation</class>
</plugin>

The validation folder defines the validation that GeoServer makes use of. Validation is used to maintain the integrity of the back end database, according to user defined rules. The plugIn folder defines the possible rules, the validation folder specifies which ones should actually be used, for which featureTypes and against which attributes. A validation file must match the testSuiteSchema.xsd file, found in capabilities/validation. It contains a name, a description, and one or more tests to run. Each test has a name, a description, and a plugIn that it uses. It also supplies the appropriate arguments, as to which attributes and featureTypes to check. A sample file looks as follows:

<?xml version="1.0" encoding="UTF-8"?>
<suite xmlns="testSuiteSchema" 
       xmlns:gml="http://www.opengis.net/gml" 
       xmlns:ogc="http://www.opengis.net/ogc" 
       xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" 
       xs:schemaLocation="testSuiteSchema /data/capabilities/validate/testSuiteSchema.xsd">
  <name>IntegrityCheck</name>
  <description>Integrity Check Description</description>

  <test>
    <name>Attr Check</name>
    <description>Checks all id's are non null, non zero values.</description>
    <plugin>Null Zero</plugin>

    <argument >
      <name>attributeName</name>
      <string>id</string>
    </argument>
    <argument >

      <name>typeRef</name>
      <string>*</string>
    </argument>
  </test>
  <test>

    <name>BC Roads Length</name>
    <description>Checks that road lengths are non zero.</description>
    <plugin>Null Zero</plugin>
    <argument >

      <name>attributeName</name>
      <string>LENGTH</string>
    </argument>
    <argument >
      <name>typeRef</name>

      <string>bc_shapefile:bc_roads</string>
   </argument>
 </test>
</suite>

This checks all featureTypes to make sure that their id attribute is never null, and that the bc_roads featureType always has a LENGTH greater than 0.

GeoServer Config Files

Services.xml

Catalog.xml

featureTypes/ files

demo/ Files

Validation Files